* chore(deps-dev): bump js-yaml from 4.2.0 to 5.0.0

Bumps [js-yaml](https://github.com/nodeca/js-yaml) from 4.2.0 to 5.0.0.
- [Changelog](https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md)
- [Commits](nodeca/js-yaml@4.2.0...5.0.0)

---
updated-dependencies:
- dependency-name: js-yaml
  dependency-version: 5.0.0
  dependency-type: direct:development
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

* fix(framework): use js-yaml v5 named export in validate-yaml

js-yaml 5.0.0 is pure ESM and drops the default export. Switch to the
named { load } import so the yaml-validity hook stops throwing the
missing default export error.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com>

…an (#271)

Four-action plan skill (gather/explore/wireframe/plan), unified feature-folder artifact layout (brainstorm/spec/plan/phases/review), implement reads the new layout with per-plan and per-phase status tracking.

Closes #292
Closes #265
Closes #276

* docs(framework): add dominance checks to review and rules

Dominance issues were easy for agents to miss when a weaker rule, criterion, or documentation statement was already covered, overridden, or invalidated by a stronger element. This adds the check at the global context, rule-generation, reviewer, and review-template levels.

* docs(framework): reduce dominance check duplication

Keep the concise dominance rule in global and rule-authoring surfaces while leaving the detailed case breakdown to the reviewer. Validation now states the shared check without reimplementing reviewer classification.

* docs(framework): separate global and rule dominance checks

Keep the general dominance reminder and reviewer taxonomy separate from rule-generation specifics. Rule authoring and validation now only check for duplicate, weaker, or contradictory rule bullets.

* docs(framework): prefer intention-revealing names

Naming guidance belongs in the global project context because it applies across artifacts. This keeps the rule concise and avoids duplicating it in domain-specific rule generation flows.

* docs(aidd-context): validate rules against shared contracts

Rule validation should apply the rule-authoring and tool-path contracts instead of restating individual rule checks. The test now has a single outcome sentence rather than multiple bullet assertions.

* docs(aidd-dev): align dominance wording with review role

The reviewer should report parallel elements rather than describe adding behavior. This keeps the dominance check phrased for read-only review while preserving the same taxonomy.

Required check "lefthook (framework-local checks)" (next.json ruleset)
is published only by validate.yml, whose pull_request/push filter was
[main]. PRs targeting next never fired it, so the required status stayed
"Expected — Waiting for status" forever, deadlocking merges (e.g. #307).

Add next to both push and pull_request branch filters.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(framework): add markdown link checker

* fix(scripts): exempt template scaffold placeholder links

01-plan's plan-template.md / phase-template.md link to ./plan.md and
./phase-N.md — files the skill emits next to the generated output at
runtime (see actions/04-plan.md), never committed to the repo. The
checker flagged them as broken.

Extend the existing asset-template branch: a dot-relative target in a
*-template.md that resolves nowhere is an intentional placeholder for a
generated sibling, so treat it as ignored rather than broken. The
assets/templates fallback (used by 02-project-memory) is unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(aidd-ui): scaffold alpha plugin (0.1.0-alpha.0)

Add aidd-ui as a new plugin with a single smoke-test skill (01-hello).

Registered in marketplace.json (recommended: false) and release config; alpha status is conveyed by the 0.1.0-alpha.0 version in plugin.json. Lives on a dedicated branch off next, so it is not public until it graduates to main.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(aidd-ui): mark alpha / not-ready across surfaces

Add prominent alpha warnings to the plugin README, the homepage plugins table, and the marketplace and plugin descriptions so the not-ready status is unmistakable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Dependabot had no target-branch, so its PRs defaulted to main. main only
takes the weekly promotion PR and the auto-merged Release PR (RELEASE.md),
so dep updates landing there cut off-cycle releases (js-yaml bump shipped
v5.0.3 mid-week). Point both ecosystems at next so updates batch into the
weekly release like all other work.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

New skill aidd-vcs:00-repo-init: init a project's repository (git init, default branch, CONTRIBUTING.md, bootstrap commit) and, on request, create the remote and push. Provider- and mechanism-agnostic: host + reach (CLI, MCP, or API) resolved from VCS memory or environment, main as default-branch fallback. No hardcoded provider or fixed mechanism.

Conforms to the skill-authoring contract (R1-R13 + action anatomy).

Co-authored-by: Baptiste LAFOURCADE <baptiste.lafourcade@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci(deps): bump actions/checkout from 6.0.3 to 7.0.0 (#321)

Bumps [actions/checkout](https://github.com/actions/checkout) from 6.0.3 to 7.0.0.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@df4cb1c...9c091bb)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: 7.0.0
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* docs(framework): unify change taxonomy into one source of truth

The same change taxonomy (kind -> where it ships) was re-spelled across
branch prefix, commit type, label, and the board "Work Type" field, and
the four drifted. A maintainer got lost finding routing info.

Make aidd_docs/memory/vcs.md the single canonical home: one dense table
(kind, prefix, commit type, triage label, next/main) plus a strict
routing rule. CONTRIBUTING and RELEASE now link it instead of restating
it; the inline label table is gone. Trim labels 11 -> 8 (drop help
wanted, npm, github-actions) and stop dependabot re-adding the dropped
ecosystem labels. Add a Project 8 board playbook + label-delete note to
MAINTAINERS, and fix its stale "Work Type" reference.

Routing is derived from the branch prefix, never a label or board field.
Spec + plan recorded under aidd_docs/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(aidd-vcs): derive PR base from branch prefix, auto-apply triage label

The pull-request action resolved the base from origin/HEAD against a
candidate list (main/master/develop/staging) that omitted `next`, so a
`feat/*` PR targeted `main`. Resolve the base from the head branch's
prefix via the project-memory routing table first, falling back to the
old detection. After opening, apply the prefix's triage label when it
exists. Stays generic: reads project memory, never hardcodes `next`.
Also fix the stale `aidd_docs/` -> `docs/` prefix in the branch template.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(framework): make the routing table an actionable guide

Reframe the canonical Types table as "I want to… → I do…": add an Issue
template column and a one-line board Status flow, so a contributor finds
their row and reads off branch, label, and PR target in one glance. Still
the single source of truth — no new table, no duplication.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…326)

The skill's transversal rules still described base detection from repo
state only, omitting the prefix-based routing and auto-labelling the
action now performs. Bring the SKILL.md contract in line: base resolves
from the branch prefix via project memory (fallback to repo state), and
the matching triage label is applied after opening.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(aidd-refine): align 02-05 skills with skill contract

Bring challenge, condense, shadow-areas and fact-check skills to the
04-skill-generate contract and concise, plain language.

- SKILL.md routers: `## Actions` header, plain-path references/assets,
  drop empty None. sections
- actions: singular Input/Output, no pipeline-variable notation, bold
  process labels, no frozen data blocks
- move challenge report skeleton to a new assets/report-template.md
- extract fact-check output-discipline into a cited reference
- shorten the four skill descriptions to two lines

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(aidd-refine): tighten tests and trim duplication

Follow-up from a headless skill-by-skill audit against the
04-skill-generate contract.

- shadow-areas: collapse redundant Test bullets (6/8/6 -> 5/7/4),
  one-line Outputs, fix 01-detect handoff (route via 03-diff before
  02-render-report when a prior report exists)
- challenge: fix Test deal-breaker/confidence rule to match the rubric,
  drop transversal rules that restated the action
- condense: drop persistence-duplicate process step, tighten tests,
  lean the router (no inline examples)
- fact-check: shorten 03-report Output, dedupe caching guidance

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* style(aidd-refine): drop punctuation dashes for concise prose

Replace em-dash-style " - " punctuation with commas, colons, or
parentheses across skill bodies, actions, and references. Keep title
headers and the literal "(unverified - no source found)" output marker.
Also fix severity-rubric "Definition rule" -> "Decision rule" label.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(aidd-refine): harden condense and fact-check fidelity

Found by the behavioral eval harness running the skills for real.

- fact-check: add a `refuted` verdict (a source contradicts the claim,
  distinct from "no source found"); emit the unverified marker verbatim;
  forbid leaking the verification method (commands, "by inspection");
  remove "cascade exhausted ..." from the report template, which leaked
  a forbidden word the discipline bans
- condense: 01-condense must emit the exact `Condense: ON (<level>).`
  line, since 02-stats and the hook parse it from the transcript

* test(aidd-refine): add behavioral skill-eval harness

Runs each refine skill for real through a headless `claude -p` in an
isolated temp project (the worktree skill installed under a unique name,
so the local copy runs, never a stale global plugin). Deterministic
checks by default; `--judge` adds an LLM grader for fuzzy outcomes.

Local / opt-in only (metered, no `claude` in CI), so not a CI gate.
Covers shadow-areas, fact-check, condense, challenge; brainstorm is
interactive and out of scope.

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…esign (#314)

Collapse the SDLC agent trio (planner/implementer/reviewer) into two leaf
agents, executor + checker, with the 00-sdlc orchestrator owning planning
itself. Enforce recipe-not-spawn: only the orchestrator spawns, recipe
skills focus on themselves and never name other skills or the SDLC.

- executor runs 02-implement, checker runs 05-review (embedded checklist).
- executor never holds 01-plan (structural immutability).
- 05-review gains a relevancy axis (fit/conform/rot) into one review.md.
- commit, pull-request, and assert defer to project memory (vcs.md,
  coding-assertions.md) over bundled defaults; ship stops dictating the
  commit format.
- pull-request is fully VCS-tool-agnostic.
- all flow skills renormalized to the skill-authoring contract; orphan
  assets and a leaked user-stories WIP duplicate removed.

Net +673/-1269. Refs #253.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…#328)

When the user asks to delete or remove code, the refactor skill is now a
trigger target and routes straight to the cleanup action. The cleanup action
sweeps for orphaned references a deletion leaves behind, so removals also clean
up imports, tests, docs, and config that pointed at the deleted symbol.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(aidd-context): unify and trim agent instruction template

- Merge best rules from CLAUDE.md and the project-memory AGENTS.md template into one focused set
- Cut aspirational/duplicate lines (goal-driven, redundant simplicity/anti-sycophancy/sureness restatements)
- Keep high-impact rules: evidence-over-assertion, quote-shortest-line, dedup meta-rule, intention-revealing names
- Align root CLAUDE.md: reference parent for shared behavior, keep framework specifics

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): sync CLAUDE.md with agent template, tighten rules

- Make CLAUDE.md a true instance of the project-memory AGENTS.md template (same rules and structure; only title, placement bullet, and filled memory block differ)
- Push CLAUDE.md-only rules up into the template: surface tradeoffs, solve own issues first, check it is good practice, less-is-more folded into Communication
- Add focus rule: stay focused, not scattered (keeps freedom, no scope-creep framing)
- Drop the anthropomorphize line; ban em-dashes alongside emoji

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): apply reviewer fixes to agent template rules

- Dedup anti-sycophancy (3 bullets into 1) and brevity (2 into 1)
- Add output-token rule: no preamble or recap
- Operationalize focus: flag unrelated issues, detour only if blocking
- Clarify the good-practice check

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): swap dedup meta-rule for a no-guessing rule

- Add: don't guess APIs/signatures/flags/behavior, read source or docs first (prevents hallucination, the top dumb-failure mode)
- Remove: the dedup meta-rule (off the runtime objectives; belongs in a standards doc)
- Keep intention-revealing names and the first-message greeting

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): scan-first response style and clarify-scope rule

- Rewrite brevity rule: telegraphic scan-first style for chat (arrows, fragments), normal prose for docs, full prose for security/irreversible/order-dependent
- Extend no-preamble rule to ban trailing next-step padding
- Add: ask one sharp question to pin down scope before an ambiguous or expensive build

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): add parallel-execution rules to agent template

- Batch independent operations in one pass, not one at a time (full test suite, not test by test)
- Fan out independent subtasks to parallel subagents

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): fix rule tensions and add next-step output rule

- Merge simple-beats-clever into surgical changes
- Make exceeding the ask an explicit exception, not the default
- Gate subagent fan-out to genuinely large or parallelizable work
- Broaden the scan-first clarity exception to any nuanced explanation
- Reframe output rule: no suggestion menus, but always state the single next action

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): restore dedup rule, soften fan-out to orchestrators

- Restore the single-source-of-truth rule removed earlier (downstream projects keep it)
- Soften fan-out: only when you own the overall flow, per docs/ARCHITECTURE.md spawning boundary
- Drop the test-suite example from the batch rule

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): bold rule heads and tighten wording

- Bold the lead directive of each rule for scannability
- Trim wording where it loses no meaning (notably the dedup rule)
- Memory block unchanged (tooling-managed, must stay live)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): clarify escalation, knowledge, and tradeoff rules

- Solve-your-own-issues: try yourself first, escalate to the human (names the target)
- Drop the vague good-practice clause; keep don't-assume-knowledge-is-current
- Surface tradeoffs and evaluate their impact (replaces vague confusion)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): allow commit/push inside authorizing flows

Agents running inside an authorizing flow (e.g. the SDLC) may commit/push; the default still blocks unprompted commits.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): simplify commit rule exception for allowed agents

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(aidd-context): revert commit rule to simple user-asks default

Drop the vague allowed-to escape hatch; authorized flows grant their own agents in their own definitions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(dev): bring 04-audit to the skill-authoring contract

- SKILL.md: rename "Available actions" to "Actions", fold the routing and
  output-contract prose into concise transversal rules, drop the
  redundant action-include list and the `->` arrows, and trim the
  description so it no longer names sibling skills.
- 7 pillar actions: singular prose Input/Output (no frozen YAML),
  one-word bold step labels, bullet-list Test, and no cross-skill
  handoff naming (the audit reports, it does not route fixes).
- README: drop the dead `impeccable` skill reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): bring 06-test to the skill-authoring contract

- SKILL.md: add what+when+Do-NOT triggers to the description, rename
  "Available actions" to "Actions", fold routing into a flow line, drop
  the redundant include list.
- actions: singular prose Input/Output (no frozen YAML), one-word bold
  step labels, bullet Test. Remove the "spawn a sub-agent" instruction
  from test-journey (a recipe never spawns).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): bring 07-refactor to the skill-authoring contract

- SKILL.md: rename "Available actions" to "Actions", fold routing,
  audit-handoff, and conventions into transversal rules, drop the
  redundant include list and the description's em-dash and sibling-skill
  names. Keep the push-not-pull audit-fed rule intact.
- 4 axis actions: singular prose Input/Output (no frozen YAML), one-word
  bold step labels, bullet Test, and no cross-skill naming (architecture
  recommends planning without naming the plan skill).
- README: drop the dead `impeccable` skill reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): bring 08-debug to the skill-authoring contract

- SKILL.md: add what+when+Do-NOT triggers, rename "Available actions" to
  "Actions", fold routing into a flow line, drop the redundant include
  list, surface the asset and reference.
- 3 actions: singular prose Input/Output (no frozen YAML), one-word bold
  step labels, bullet Test. Fix the same-skill reference slug
  (reflect_issue to reflect-issue) and the stray prose arrow.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): bring 09-for-sure to the skill-authoring contract

- SKILL.md: replace the Context/Environment/Execution-flow prose with an
  Actions table and transversal rules, add a Do-NOT clause, drop the
  empty "Environment: None" section and the redundant include block, and
  label the template as an asset, not a reference.
- 3 actions: singular prose Input/Output (no frozen YAML), one-word bold
  step labels, bullet Test, prose arrows fixed.
- Extract action 03's inline worker-prompt to assets/ and its log-entry
  format to references/ so the action holds pure anatomy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(dev): regenerate catalog after skill refactors

* refactor(pm): bring ticket-info, user-stories-create, prd to the contract

- SKILL.md x3: rename "Available actions" to "Actions", drop the empty
  References/Assets/External-data placeholder sections (R9).
- actions x3: singular prose Input/Output (no frozen YAML), one-word bold
  step labels, no prose arrows, bullet Test, and correct `@../assets/`
  citation paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(vcs): bring repo-init, release-tag, issue-create to the contract

- SKILL.md x3: rename "Available actions" to "Actions", drop empty
  References/External-data placeholder sections, fix the repo-init
  description (colon not dash, no sibling-skill names), correct asset
  citation paths to `@assets/`.
- release-tag and issue-create actions: singular prose Input/Output (no
  frozen YAML), one-word bold step labels, no prose arrows, bullet Test,
  `@../assets/` citation paths. repo-init actions were already conformant.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(orchestrator): hygiene-norm 00-async-dev

Remove every em-dash (headers to colons, prose to commas), rename the
plural `## Inputs`/`## Outputs` action headers to singular, and fix the
stray prose arrows. The skill's router, three sub-flow tables, and 21
nested actions were already structurally sound, so this is a hygiene
pass, not a body rewrite.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(orchestrator): convert remaining mapping arrows to → in async-dev references

* refactor(context,ui,refine): norm bootstrap, hello, condense

- 01-bootstrap: rename "Available actions" to "Actions", drop the
  External-data section that named another skill's path, fix the body
  dash. Rewrite the 5 actions to the anatomy: singular prose Input/Output
  (no frozen example blocks), one-word bold step labels, bullet Test, no
  "Depends on" section. The candidate-audit spawn is preserved as-is.
- 01-hello: add the missing title and `## Test`, rename the header, drop
  the empty `## Inputs - none`.
- 03-condense: fix the `@references/` citation, drop the non-norm
  External-data section (the hook is already covered in the stats
  action), bullet the stats Test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: clear residual contract nits across skills

- async-dev: drop the non-norm "## Depends on" sections from all 18
  nested actions (the SKILL flow already states the sequence). Includes
  a linter pass normalizing em-dashes to `--`.
- 10-todo: rename the action's plural Input/Output headers to singular.
- 12-cook: drop the em-dash separators in the recipe template asset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: use plain paths in SKILL.md, no @ (per skill-template)

The canonical scaffold prescribes plain paths in the SKILL.md
References/Assets sections ("Plain paths, no @"); @ includes belong only
in action files, which load them. Strip @ from every SKILL.md path
listing and citation across all skills, including the flow skills merged
earlier. The only @ left are the literal `@claude` webhook triggers in
async-dev.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: rewrite skill descriptions to the skill-generate norm

Descriptions now follow the contract shape: a verb-led what-clause, then
"Use when the user wants to <natural intents>", then a plain "Not for
<overlap>". Drop every reference to another skill and every /command
token (slash commands are tool-native), and fix the semantics that were
wrong, notably the PRD, which is generated from a need, idea, or
brainstorm and is upstream of user stories, not derived from them.

Covers the refactored skills plus the gold-standard and merged skills
that carried sibling references or slash tokens (onboard,
project-memory, brainstorm, shadow-areas, fact-check, todo, commit,
pull-request).

Also collapse the few multi-word action step labels left from the prior
pass to the one-word bold lead the anatomy requires.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(pm): make the PRD template solution-agnostic

Headless testing surfaced a contradiction: the bundled prd-template.md
shipped 15 sections including Technical Architecture, Tech Stack, and
Data Model, which directly violate the skill's "never include technical
implementation detail" rule and the action's own 8-section spec. The
action's Test also checked for headings the template did not have.

Rewrite the template to the action's eight solution-agnostic sections
(Overview, Problem Statement, Goals, Non-Goals, User Stories, Acceptance
Criteria, Dependencies, Open Questions) with an HTML-comment header so no
frontmatter leaks into output, and tighten the action Test to assert
those headings and the absence of any solution detail. Re-verified
headless: 8 sections present, zero solution detail.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(context): add missing ## Output to cook 02-upsert action

* docs(context): add a description size rule to the skill contract (R5)

skill-generate produced oversized descriptions every run because R5 told
it to "over-list" triggers with only a 1024-char ceiling and no size
target. Add the missing rule: two lines max, ~240 chars, straight to the
point, length serves recall not completeness. Also fix R5 to match the
norm already enforced: lead with a verb, state triggers as "Use when the
user wants to ...", never name another skill, never write a /command
token (slash commands are tool-native). Update the template placeholder
to match.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: trim 22 skill descriptions to the 2-line size rule

Apply the new R5 size rule to every description over the limit: two
lines, ~240 chars, straight to the point, same shape (verb-led, "Use
when the user wants to ...", plain "Not for ..."). Also drop the last
two sibling-skill mentions (onboard/explore) so no description names
another skill. 02-user-stories is trimmed in the working tree and left
for its own commit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(context,refine): close 3 defects found by the headless suite

Generic and concise, never naming a specific tool or session mode:
- explore: detect a tool only by its own mapped surfaces, never a
  shared parent directory, so a bare CI folder no longer counts as a
  tool. Add the presence-signal rule to ai-mapping and key survey step 1
  to it.
- onboard: tighten the silent-read rule so action 01 emits nothing even
  in a single turn; the first words come from orient.
- fact-check: harden the report scrub into a line-by-line final gate and
  drop the named output-mode list (no "terse/caveman/condensed") in
  favor of "any active output mode".

Re-tested headless: explore and onboard hold; fact-check's wording is
clean, though a forced session output mode can still bleed a summary
line at runtime, which is a host-mode interaction, not a skill gap.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(vcs,dev): split commit/pull-request into step actions, fix audit folder

Model the real workflow as actions instead of one monolithic action:
- commit: collect (stage one concern) → message → commit (push when
  asked). Drop the retry loop: a hook that rejects the commit is not
  this skill's job, it reports which hook and why and stops, only
  re-staging files a hook auto-formatted.
- pull-request: collect (resolve base, gather commits) → draft (title
  and body) → create (open draft, label). Conventions live in
  transversal rules.
- audit: one dated folder per run (aidd_docs/tasks/<yyyy_mm>/
  <yyyy_mm_dd>_audit/, like a feature folder) defined once in a
  transversal rule; each pillar action names only its file
  (architecture.md, security.md, ...); a full run adds report.md.

Headless-tested: commit chain produces a conventional commit; a failing
pre-commit hook reports and stops with no commit and no loop; audit
writes the pillar file into the dated folder.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(vcs): keep the VCS convention in one transversal rule, no baked example

Drop the project-specific `feat/ → next` example from the pull-request
skill and de-duplicate the convention source: `vcs.md` now appears only
in the SKILL transversal rule (where + fallback), and the actions just
apply it ("per the project's convention"). The concrete branch examples
stay in the bundled fallback asset (branch.md), where examples belong.
The skill reads the project's convention from memory instead of assuming
one, so behavior is project-driven, not hardcoded.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(dev): audit full run writes every pillar file plus report.md

The rule was ambiguous, so a full run wrote only the merged report.
Make it explicit: every pillar that runs always writes its own
<pillar>.md, and a full run additionally writes report.md. Re-tested
headless: a full run produced all 7 pillar files plus report.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: quick conciseness wins across skills

Two mechanical passes against the AI-template feel, no behavior change:
- Drop the filler "## Default flow" sections: delete the pure
  single-action ones ("the router dispatches to X whenever a phrase
  appears"), and inline the real-flow ones as one tight line under the
  actions table.
- Strip obvious embedded git commands from action prose ("the current
  branch" not the rev-parse incantation, "the remote URL" not the
  remote-get-url one), keeping the runnable ones in ## Test. The onboard
  read-project step also loses its hardcoded .github path.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(vcs,dev): de-duplicate what the transversal rule already owns

Actions were restating their skill's transversal rule:
- repo-init: both Resolve steps repeated the whole "from VCS memory, else
  the environment, else main" resolution. They now just say "resolve the
  default branch and provider" / "resolve the host"; the transversal rule
  owns how.
- release-tag: the bump step dropped "only" (the transversal already
  scopes the bump commit to version-manager files).
- assert: dropped the Boundary step that repeated "stop only when the
  final sweep passes."

No behavior change: each convention has one home, the action defers.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): restore assert Boundary step (loop stop belongs in the process)

The de-dup pass dropped it as a duplicate of the transversal stop rule,
but a fix-loop's termination is part of the process, not just a passive
convention. Keep it explicit where the loop decision happens.

* refactor: apply four cross-skill principles (args, heavy steps, guards, plain words)

- Tool-agnostic input: `$ARGUMENTS` (a Claude-only token other hosts
  won't read) becomes the plain word "the arguments" across 16 skills.
  command-generate keeps it, since the token is what it teaches.
- One job per step: split plan's overloaded `Write` step into Folder /
  Fill / Show.
- Sequence vs guards: implement's `02-execute` separates the Open / Code
  / Assert loop from the Blocked and Drift stop conditions, which are no
  longer numbered steps.
- Plain words: implement's `Branch` drops the embedded `git checkout -b`
  for "create a feature branch".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor: lighten the remaining heavy steps (one job per step)

Split learn's Ask into Show + Decide and ship's Gate into Gate +
Freshness; tighten sdlc's Iterate and refactor's architecture Source.
No heavy (>320-char) steps remain.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): separate guards from sequence in 06-test

- test-journey: the Failure handling is part of the Walk, not a peer
  step; fold it under Walk as a sub-bullet.
- test: drop the Boundary step that restated the transversal rules
  (functional only, never compromise quality); one-at-a-time stays
  implicit in the generate-then-next loop.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(dev): make execute stop-conditions a Guard step with sub-bullets

The free-floating 'Stop the loop on either condition' block diverged
from the action anatomy. Express it as a numbered Guard step whose
conditions are sub-bullets (the anatomy's form for a branch), keeping
Blocked and Drift as bullets, not peer steps. Left in the action, not
the transversal rules: these guard the execute loop only.

* fix(dev): review must not assume 'main' as the diff base

All three review actions hardcoded `git diff main`. Resolve the diff
against the repository's default branch instead, never a blind main,
matching the pull-request skill's base handling.

* fix(dev,vcs): two blockers the deep audit caught

- for-sure: the spawned-worker prompt had no payment/destructive
  carve-out, and the loop never consumed the worker's stop status, so a
  worker that halted on a money gate was retried, re-triggering the
  spend. Add the carve-out to the worker prompt and make the loop
  surface a gate stop and halt instead of retrying.
- release-tag: a tagless repo fell back to a fictitious v1.0.0 and then
  ran `git log v1.0.0..HEAD`, which aborts. With no prior tag, list every
  commit on the branch instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: clear semantic defects from the deep audit (batch 1)

- prd task-template: drop the stray brace in "## Main step 1}".
- command-generate README: correct the stale "# 10" heading to "# 07".
- issue-create template: "GitHub issues" to "issues in the configured
  tracker" (the skill is tool-agnostic).
- 01-plan SKILL: drop the dangling reference to a mermaid-conventions.md
  that does not exist in the skill and no action uses.
- commit and pull-request READMEs: replace the stale "single action"
  description with the three-action chain each skill now has.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: semantic defects from the deep audit (batch 2)

Mostly Output/Test mismatches where the Test under-verified or
contradicted the declared Output, plus a few wording bugs:
- sync Tests to the full Output (ticket-info six fields, cook README
  index row, debug flowchart + confidence, test-journey full fields).
- audit: rename the template header to "## Top actions" so all seven
  pillar Tests match it.
- spec: assert "every required section" (the validator marks some
  optional), matching the Process.
- fact-check: re-render restyled lines in plain prose instead of
  deleting them (deleting lost content).
- plan phase-template: legend now reads deleted/created/modified,
  matching the upstream modify/create/delete vocabulary.
- todo: drop "using template" (no such asset); learn-sync names the
  updated files (its Test wants names, not a count); agent-generate
  Clarify now asks the model (it is a declared output); test marks a
  declined behavior pending; refactor allows a security-fix regression
  test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(pm): replace user-stories-create with the six-action user-stories skill

Rename and rebuild: 02-user-stories-create (one monolithic action) is
replaced by 02-user-stories, a six-action chain (clarify-scope,
split-epic, draft-stories, estimate-impact, prioritize, sync-tracker)
with INVEST, a Definition of Ready and a functional Definition of Done.
Update the plugin manifest, catalogs, marketplace, READMEs, and the
upgrade map. Applies its two audit findings: estimate-impact now lists
dependencies in its Output, and clarify-scope no longer restates the
transversal lean-clarification rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: memory-deduplication diagnosis and dedup plan

Add the memory-duplication diagnosis and the memory-dedup feature folder
(plan, phases, empirical results), plus the two one-line doc touches that
came with that work.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(context): repair the garbled scaffold-docs action label

The action-table cell had become 'Create the `folder structure' with an
unclosed backtick and the lost aidd_docs/ reference. Restore it to
'Create the `aidd_docs/` folder structure'.

* fix(skills): resolve semantic contradictions from deep audit

Align action contracts with their stated outputs, tests, and SKILL rules:
- onboard: orient stops at offer+capture; 03-act owns acting on every choice
- sdlc ship: implement the promised on_default_branch gate (commit nothing)
- skill-generate: contract is R1-R13; draft output covers plugin-source mode
- agent-generate: capture picks one name, output/test follow
- bootstrap: pick a candidate by name; fold cost check into the rationale
- hook-generate: scope tool-paths to commonly supported moments, no gap promise
- challenge: drop orphan report section; make the 100% confidence tier exclusive
- shadow-areas: symmetric dispatch; template renders only categories with gaps
- assert-frontend: output schema matches the candidate-causes step
- pull-request README: list only the assets that ship

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(skills): drop host tokens, make two descriptions verb-led and plain

- review, mermaid: verb-led descriptions, plain "Not for", under the limit
- onboard, commit, condense, implement: drop host-specific slash and
  $ARGUMENTS tokens from instruction prose for plain capability language

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(skills): drop passive restatements the transversal already owns

Remove trailing reminder clauses that echo a SKILL transversal rule while
the step's primary action stays intact: explore (skip-surface, no-advice,
no-assume), debug (no drive-by refactors), mermaid (no unconfirmed node),
learn (preserve edits), review (never patch, x2), assert-architecture
(never fix), spec (solution-agnostic). Load-bearing guards, loop
terminators, and point-of-action safety constraints are kept.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(spec): keep the behavioral half of the build-step guard

The transversal owns the artifact property (solution-agnostic), but not the
agent action: restore "Do not explore the codebase." so the step still
forbids reading the code, dropping only the redundant property restatement.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* refactor(onboard): cut meta-commentary from orient step 7

The step instructs; explaining that 03-act delegates here is noise. The
handoff is already documented from 03-act's side.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(skills): repair structural anatomy bugs from deep audit

- cook: asset ref needs the parent path (@../assets) to resolve from actions/
- agent-generate README: header number 06, not 09
- command-generate tool-paths: drop the duplicated table header row
- debug task-template: remove stray brace in "## Main step 1"
- todo: dangling colon ends the Report step as a sentence
- for-sure tracking template: drop skill-metadata frontmatter that leaked
  name/description/argument-hint into every generated plan file

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(rule-generate): correct sibling @-path in references

@-paths are file-relative (actions use @../references/...), so from inside
references/ the sibling is @rule-authoring.md, not @references/... which
resolved to references/references/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(skills): repair four defects surfaced by the headless behavioral test

- agent-generate: Codex TOML rule mandated single-quote literals, which
  cannot hold an apostrophe; use a double-quoted basic string with escaping
- async-dev: actions 03/04/05 read assets/<t> but the templates live at
  assets/setup/<t>; restore the setup/ segment so the Read resolves
- shadow-areas: empty source stopped with an uncategorizable blocker gap
  that broke the locked-category rule; stop with a plain warning, no gap
- todo: the mandated per-executor refine resolved to an interactive-only
  skill that blocks in autonomous subagents; fall back to inline refine

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(skills): wire onboard hand-off, drop unused issue type field

- onboard: orient now offers "run it in a fresh session instead", so
  03-act's Hand off outcome is reachable instead of a dead branch
- issue-create: drop the type field from Input/Output/Validate; Create
  never applied it and gh issue create has no native type flag

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(docs): repair broken markdown links failing CI Validate

- regenerate plugin CATALOGs: drop the deleted 05-pull-request-list section
  (aidd-vcs) and the stale 01-plan mermaid-conventions row (aidd-dev)
- task scratch docs: the @-build illustration used literal [x](../x) link
  syntax the checker resolved as a path; reword to prose

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ctions (#347)

Memory generation restated the same fact across files (architecture vs
codebase-map, integration internal flow, stack libs) because templates
overlapped and the fill ran blind in parallel. Reframe ownership so each
fact has one home and others reference it.

Templates
- architecture: drop Structure (codebase-map owns areas + entry point);
  Stack lists cross-cutting libs only, a capability's lib lives in its file
- integration: reframe to external/third-party services (drop Internal,
  which duplicated architecture's flow)
- api/navigation: scope routes to server vs client

Actions / rules
- 03: fill is no longer blind in parallel; each template knows what earlier
  ones captured
- SKILL: split rules into Memory rules (content) and Action rules (process);
  add "one fact, one file" with the define-here / reference-elsewhere nuance
- 04: semantic dedup review step (no fact's definition duplicated)
- new references/memory-block.md; drop capability-signals' redundant section

Validated headless on three stacks (cli, kairos web/mobile, kairos existing):
definition-level duplication gone, files stay self-contained.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Brainstorm (guide that enforces a skippable foundation, then a project-
adapted menu) and a 4-phase plan, hardened across three fixture-matrix
dry-runs: flow-walk owns the default, signal map ranks secondary tools,
read-once with a session ledger that tracks done/skipped steps.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace re-read-every-loop with a single reusable snapshot plus a session
ledger of run/skipped steps. 01 produces the snapshot (cheap signals + a
bounded richer read) and the ledger; 03 writes it (run → done, different
step → skipped); 02 consumes it (a stage is met by a disk fact OR the
ledger), so a just-run or declined step is never re-suggested even when it
left no file behind. journey.md points to 02's met-definition, no restatement.

Behaviorally verified: empty-repo re-nag, off-disk Track completion, and the
skip path all advance instead of looping.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

02-orient marks a foundation stage as the loud pre-selected default with an
explicit branch — architect a stack on an empty repo, set up the memory bank
on a content repo with weak memory — rendered as the first choice tagged
(recommended), always skippable. SKILL keeps suggest-never-force with the
skippable + skip-remembered note. 01 pins that a docs/README-only repo counts
as empty.

Behaviorally verified: empty→architect, weak-memory→memory, skip excludes the
default from the next loop (no re-nag), and the gate never blocks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Push detail into references/assets so the actions stay one line:
- references/signals.md: the signal catalogue (cheap + a bounded richer read:
  code-quality sample, bug-marker scan) and the capability map (signal →
  stage-gated secondary tool)
- assets/menu.md: the menu shape — default, ranked secondary tools (≤~5),
  a never-dropped footer, need-stage and end-stage (review-never-skipped) rules
- 02-orient: place → rank → resolve → brief → assemble, one line each
- journey.md: cumulative-stage placement made explicit (a plan implies the
  need is clarified/tracked); open-PR row reviews before ship; tool ranking
  deferred to signals.md, no duplication

Behaviorally verified: mid-build → Build alone + add-tests/audit/debug;
open-PR → Review then Ship; rough idea → no loud default, Clarify first;
empty/code-no-memory foundation + ledger advance regress clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- move the per-choice outcome table into references/outcomes.md; 03-act
  becomes a thin act + ledger dispatch (722 -> 171 words)
- description no longer uses a colon

Verified live (headless claude -p): the menu and the "explain the step"
outcome render correctly from the new reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Rewrite the four descriptions that used a colon (cook, assert, async-dev,
repo-init) into two sentences, and add the rule to R5 in skill-authoring.md
so it holds going forward. assert also drops "Do NOT use to" for plain "Not for".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-authored-by: aidd-bot[bot] <290648294+aidd-bot[bot]@users.noreply.github.com>

# Conflicts:
#	.claude-plugin/marketplace.json
#	.release-please-manifest.json
#	CHANGELOG.md
#	plugins/aidd-pm/.claude-plugin/plugin.json
#	plugins/aidd-ui/.claude-plugin/plugin.json
#	plugins/aidd-vcs/.claude-plugin/plugin.json